Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Refine the public API interface #3

Merged
merged 14 commits into from
Oct 11, 2024
Merged

Refine the public API interface #3

merged 14 commits into from
Oct 11, 2024

Conversation

alext
Copy link
Member

@alext alext commented Oct 7, 2024

What

Refine the public interface of this package:

  • Change names to match the Python version where it makes sense to.
  • Remove unnecessary bits from the public interface.
  • Fix the types of some method params to better reflect what they are ([]byte vs string etc.)
  • Introduce some error type to make it easier to check errors in consuming code.
  • Simplify the default constructors.

Why

Get the public API interface right before we start tagging releases and using this in anger so that it's easier to maintain backwards compatibility in future releases.

Notes for reviewer.

This is a fairly large refactoring of the API surface etc, although the core algorithms are unchanged. This may be easier to review commit-by-commit

alext added 14 commits October 7, 2024 10:46
These simply generate a new hash instance, only to call Reset() on it
and then discard it, which is a wasted allocation etc.

They look to be a hangover from before 7dd818e where DigestMethod used
to hold a persistent instance of hash.Hash, and therefore needed
resetting before each use.
DigestMethod is already a func() hash.Hash, so there's no longer a need
to wrap it in an anonymous function with the same signature to call it.
Rename Signature to Signer to match and better express what they cover.

Also rename the GetSignature and VerifySignature methods to match Python
These aren't really strings.  They were being cast to string, only to be
cast back to []byte in HMACAlgorithm. Additionally, these contain
arbitrary bytes, so aren't printable, and therefore don't make sense to
handle as strings.
Ensure this is tested against examples generated by the Python
implementation to ensure compatibility. Include tests that invalid
signatures fail to Unsign.
This can simply call the wrapped Signer's Sign method instead of
duplicating it. This makes it symmetrical with Unsign.
Reduce it to the Sign and Unsign methods on signers as these are the
ones needed by consumers.  It's also easier from a
backwards-compatibility PoV to start with a narrow interface and widen
it if necessary, than it is to later need to narrow it.

With this, I've also tweaked the naming of some parameters to make them
clearer.
Most of the time when using this we want the parameters set to the
defaults for interoperability with Python. This removes all the extra
options from the default constructos, and adds NewSignerWithOptions etc
constructors to allow changing the default for the edge-cases where this
is needed.
This makes it much clearer to use as there's no need to look up what
units it's in etc.
There's no need for these to be public.  If a need arises this can be
changed later, but we can't make them private later without breaking
backwards compatibility.
By moving the key derivation to the constructor, the Sign method no
longer can return an error, which simplifies usage.

It's also a bit more efficient as the key is only generated once, intead
of for each sign/verify operation. It also means the secretKey and salt
etc no longer need to be stored on the Signer, which simplifies the
struct a bit.
We're calling strings.LastIndex immediately afterwards, which returns -1
if the substring isn't found, so we can use this result to return the
error.
Add error types for all invalid signature errors, as well as a specific
one for an expired signature. This will allow consumers to more easily
respond to these error conditions.
This ensures that they're only using the public API for the package.
@alext alext changed the title Refine the public interface Refine the public API interface Oct 7, 2024
@alext alext requested a review from a team October 7, 2024 16:06
@alext alext merged commit 9c74755 into master Oct 11, 2024
1 check passed
@alext alext deleted the interface_naming branch October 11, 2024 13:51
@alext alext restored the interface_naming branch October 11, 2024 13:54
@alext alext deleted the interface_naming branch October 11, 2024 13:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant